/*-------------------------------------------------------------------------
 *
 * dshash.h
 *	  由动态共享内存区域支持的并发哈希表。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * IDENTIFICATION
 *	  src/include/lib/dshash.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef DSHASH_H
#define DSHASH_H

#include "utils/dsa.h"

/* 表示哈希表的 opaque 类型。 */
struct dshash_table;
typedef struct dshash_table dshash_table;

/* 一个可以与其他进程共享的 dshash_table 句柄。 */
typedef dsa_pointer dshash_table_handle;

/* 哈希值的类型。 */
typedef uint32 dshash_hash;

/* 用于比较键的函数类型。 */
typedef int (*dshash_compare_function) (const void *a, const void *b,
										size_t size, void *arg);

/* 用于计算键的哈希值的函数类型。 */
typedef dshash_hash (*dshash_hash_function) (const void *v, size_t size,
											 void *arg);

/*
 * 创建或附加到哈希表所需的参数集。成员 tranche_id 和 tranche_name 在
 * 附加到现有哈希表时无需初始化。
 *
 * 即使在附加时也必须提供比较和哈希函数，因为我们不能安全地共享函数指针
 * 在后端之间。应提供参数变体或非参数变体的其中之一；其他函数指针应为
 * NULL。如果提供了参数变体，则传递给创建和附加函数的用户数据指针将
 * 传递给哈希和比较函数。
 */
typedef struct dshash_parameters
{
	size_t		key_size;		/* 键的大小（条目的初始字节） */
	size_t		entry_size;		/* 条目的总大小 */
	dshash_compare_function compare_function;	/* 比较函数 */
	dshash_hash_function hash_function; /* 哈希函数 */
	int			tranche_id;		/* 用于锁的 tranche ID */
} dshash_parameters;

/* 仅供 dshash.c 使用的私有类型的前向声明。 */
struct dshash_table_item;
typedef struct dshash_table_item dshash_table_item;

/*
 * 顺序扫描状态。细节被暴露是为了让用户知道存储大小，但它应当被
 * 调用者视为不透明类型。
 */
typedef struct dshash_seq_status
{
	dshash_table *hash_table;	/* dshash 表正在工作 */
	int			curbucket;		/* 我们所在的桶编号 */
	int			nbuckets;		/* dshash 中的桶总数 */
	dshash_table_item *curitem; /* 我们当前的位置 */
	dsa_pointer pnextitem;		/* 指向下一个项目的 dsa 指针 */
	int			curpartition;	/* 我们所在的分区编号 */
	bool		exclusive;		/* 锁定模式 */
} dshash_seq_status;

/* 从哈希表创建、共享和销毁。 */
extern dshash_table *dshash_create(dsa_area *area,
								   const dshash_parameters *params,
								   void *arg);
extern dshash_table *dshash_attach(dsa_area *area,
								   const dshash_parameters *params,
								   dshash_table_handle handle,
								   void *arg);
extern void dshash_detach(dshash_table *hash_table);
extern dshash_table_handle dshash_get_hash_table_handle(dshash_table *hash_table);
extern void dshash_destroy(dshash_table *hash_table);

/* 查找、创建、删除条目。 */
extern void *dshash_find(dshash_table *hash_table,
						 const void *key, bool exclusive);
extern void *dshash_find_or_insert(dshash_table *hash_table,
								   const void *key, bool *found);
extern bool dshash_delete_key(dshash_table *hash_table, const void *key);
extern void dshash_delete_entry(dshash_table *hash_table, void *entry);
extern void dshash_release_lock(dshash_table *hash_table, void *entry);

/* 顺序扫描支持 */
extern void dshash_seq_init(dshash_seq_status *status, dshash_table *hash_table,
							bool exclusive);
extern void *dshash_seq_next(dshash_seq_status *status);
extern void dshash_seq_term(dshash_seq_status *status);
extern void dshash_delete_current(dshash_seq_status *status);

/* 包装 memcmp 和 tag_hash 的便利哈希和比较函数。 */
extern int	dshash_memcmp(const void *a, const void *b, size_t size, void *arg);
extern dshash_hash dshash_memhash(const void *v, size_t size, void *arg);

/* 调试支持。 */
extern void dshash_dump(dshash_table *hash_table);

#endif							/* DSHASH_H */
